<!DOCTYPE html SYSTEM "about:legacy-compat">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Catalina Functional Specifications (8.0.36) - JDBCRealm</title><meta name="author" content="Craig McClanahan"><script type="application/javascript" data-comments-identifier="tomcat-8.0-doc/funcspecs/fs-jdbc-realm">
    "use strict"; // Enable strict mode

    (function() {
      var thisScript = document.currentScript;
      if (!thisScript) { // Workaround for IE <= 11
        var scripts = document.getElementsByTagName("script");
        thisScript = scripts[scripts.length - 1];
      }
      document.addEventListener("DOMContentLoaded", (function() {
        var commentsDiv = document.getElementById("comments_thread");
        var commentsShortname = "tomcat";
        var commentsIdentifier = "http://tomcat.apache.org/" +
          thisScript.getAttribute("data-comments-identifier") + ".html";

        (function(w, d) {
          if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
            var s = d.createElement("script");
            s.type = "application/javascript";
            s.async = true;
            s.src = "https://comments.apache.org/show_comments.lua?site=" +
              encodeURIComponent(commentsShortname) +
              "&page=" + encodeURIComponent(commentsIdentifier);
            d.head.appendChild(s);
          } else {
            commentsDiv.appendChild(d.createTextNode("Comments are disabled for this page at the moment."));
          }
        })(window, document);
      }), false);
    })();
  </script></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="http://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="http://www.apache.org/" target="_blank"><img src="../images/asf-feather.png" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Catalina Functional Specifications</h1><div class="versionInfo">
          Version 8.0.36,
          <time datetime="2016-06-09">Jun 9 2016</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Administrative Apps</h2><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul></div><div><h2>Internal Servlets</h2><ul><li><a href="fs-default.html">Default Servlet</a></li></ul></div><div><h2>Realm Implementations</h2><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>JDBCRealm</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Overview_of_Operation">Overview of Operation</a></li><li><a href="#Detailed_Functional_Requirements">Detailed Functional Requirements</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul>
</div><h3 id="Overview">Overview</h3><div class="text">


  <div class="subsection"><h4 id="Introduction">Introduction</h4><div class="text">

    <p>The purpose of the <strong>JDBCRealm</strong> implementation is to
    provide a mechanism by which Tomcat can acquire information needed
    to authenticate web application users, and define their security roles,
    from a relational database accessed via JDBC APIs.  For integration
    with Catalina, the resulting class(es) must implement the
    <code>org.apache.catalina.Realm</code> interface.</p>

    <p>This specification reflects a combination of functionality that is
    already present in the <code>org.apache.catalina.realm.JDBCRealm</code>
    class, as well as requirements for enhancements that have been
    discussed.  Where appropriate, requirements statements are marked
    <em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>

    <p>The current status of this functional specification is
    <strong>PROPOSED</strong>.  It has not yet been discussed and
    agreed to on the TOMCAT-DEV mailing list.</p>

  </div></div>


  <div class="subsection"><h4 id="External_Specifications">External Specifications</h4><div class="text">

    <p>The implementation of this functionality depends on the following
    external specifications:</p>
    <ul>
    <li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
        Java Database Connectivity</a> (version 2.0 or later)</li>
    <li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
        Java Database Connectivity Optional Package</a> (version 2.0 or later)</li>
    </ul>

  </div></div>


  <div class="subsection"><h4 id="Implementation_Requirements">Implementation Requirements</h4><div class="text">

    <p>The implementation of this functionality shall conform to the
    following requirements:</p>
    <ul>
    <li>Be realized in one or more implementation classes.</li>
    <li>Implement the <code>org.apache.catalina.Realm</code> interface.
        [Current]</li>
    <li>Implement the <code>org.apache.catalina.Lifecycle</code>
        interface.  [Current]</li>
    <li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
        base class.</li>
    <li>Live in the <code>org.apache.catalina.realm</code> package.
        [Current]</li>
    <li>Support a configurable debugging detail level. [Current]</li>
    <li>Log debugging and operational messages (suitably internationalized)
        via the <code>getContainer().log()</code> method. [Current]</li>
    </ul>

  </div></div>


</div><h3 id="Dependencies">Dependencies</h3><div class="text">


  <div class="subsection"><h4 id="Environmental_Dependencies">Environmental Dependencies</h4><div class="text">

    <p>The following environmental dependencies must be met in order for
    JDBCRealm to operate correctly:</p>
    <ul>
    <li>The desire to utilize JDBCRealm must be registered in
        <code>$CATALINA_BASE/conf/server.xml</code>, in a
        <code>&lt;Realm&gt;</code> element that is nested inside a
        corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
        or <code>&lt;Context&gt;</code> element.</li>
    </ul>

  </div></div>


  <div class="subsection"><h4 id="Container_Dependencies">Container Dependencies</h4><div class="text">

    <p>Correct operation of JDBCRealm depends on the following
    specific features of the surrounding container:</p>
    <ul>
    <li>Interactions with <code>JDBCRealm</code> will be initiated by
        the appropriate <code>Authenticator</code> implementation, based
        on the login method that is selected.</li>
    <li><code>JDBCRealm</code> must have the JDBC standard API classes
        available to it.  For a JDK 1.2 or later container, these APIs
        are included in the standard platform.</li>
    <li>When connection pooling is implemented, <code>JDBCRealm</code>
        must have the JDBC Optional Package (version 2.0 or later) APIs
        available to it.  This library is available as a separate
        download (and will be included in Tomcat binary distributions).</li>
    </ul>

  </div></div>


</div><h3 id="Functionality">Functionality</h3><div class="text">


  <div class="subsection"><h4 id="Overview_of_Operation">Overview of Operation</h4><div class="text">

    <p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
    authenticate users, and look up the corresponding security roles, from
    the information found in a relational database accessed via JDBC APIs.
    For maximum flexibility, the details of how this is done (for example,
    the names of the required tables and columns) should be configurable.</p>

    <p>Each time that Catalina needs to authenticate a user, it will call
    the <code>authenticate()</code> method of this Realm implementation,
    passing the username and password that were specified by the user.  If
    we find the user in the database (and match on the password), we accumulate
    all of the security roles that are defined for this user, and create a
    new <code>GenericPrincipal</code> object to be returned.  If the user
    is not authenticated, we return <code>null</code> instead.  The
    <code>GenericUser</code> object caches the set of security roles that
    were owned by this user at the time of authentication, so that calls to
    <code>isUserInRole()</code> can be answered without going back to the
    database every time.</p>

  </div></div>


  <div class="subsection"><h4 id="Detailed_Functional_Requirements">Detailed Functional Requirements</h4><div class="text">


    <h3>Configurable Properties</h3>

    <p>The implementation shall support the following properties
    that can be configured with JavaBeans property setters:</p>
    <ul>
    <li>Configuration parameters defining the JDBC driver to use, the
        database connection URL to be accessed, and the username/password
        to use for logging in. [Current]</li>
    <li>Configuration parameters describing the connection pool to be
        created to support simultaneous authentications. [Requested]</li>
    <li>Name of the tables to be searched for users and roles. [Current]</li>
    <li>Name of the columns to be used for usernames, passwords, and
        role names.  [Current]</li>
    </ul>

    <h3>Lifecycle Functionality</h3>

    <p>The following processing must be performed when the <code>start()</code>
    method is called:</p>
    <ul>
    <li>Establish a connection to the configured database, using the
        configured username and password.  [Current]</li>
    <li>Configure and establish a connection pool of connections to the
        database.  [Requested]</li>
    </ul>

    <p>The following processing must be performed when the <code>stop()</code>
    method is called:</p>
    <ul>
    <li>Close any opened connections to the database.</li>
    </ul>


    <h3>Method authenticate() Functionality</h3>

    <p>When <code>authenticate()</code> is called, the following processing
    is required:</p>
    <ul>
    <li>Acquire the one and only connection [Current] or acquire a connection
        from the connection pool [Requested].</li>
    <li>Select the one and only row from the user's table for this user,
        and retrieve the corresponding password column.  If zero rows (or
        more than one row) are found, return <code>null</code>.</li>
    <li>Authenticate the user by comparing the (possibly encrypted) password
        value that was received against the password presented by the user.
        If there is no match, return <code>null</code>.</li>
    <li>Acquire a <code>List</code> of the security roles assigned to the
        authenticated user by selecting from the roles table.</li>
    <li>Construct a new instance of class
        <code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
        constructor arguments:  this realm instance, the authenticated
        username, and a <code>List</code> of the security roles associated
        with this user.</li>
    <li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
        <code>GenericPrincipal</code> objects for a particular user, because
        the information in the directory server might have changed since the
        last time this user was authenticated.</li>
    <li>Return the newly constructed <code>GenericPrincipal</code>.</li>
    </ul>


    <h3>Method hasRole() Functionality</h3>

    <p>When <code>hasRole()</code> is called, the following processing
    is required:</p>
    <ul>
    <li>The <code>principal</code> that is passed as an argument SHOULD
        be one that we returned (instanceof class
        <code>org.apache.catalina.realm.GenericPrincipal</code>, with a
        <code>realm</code> property that is equal to our instance.</li>
    <li>If the passed <code>principal</code> meets these criteria, check
        the specified role against the list returned by
        <code>getRoles()</code>, and return <code>true</code> if the
        specified role is included; otherwise, return <code>false</code>.</li>
    <li>If the passed <code>principal</code> does not meet these criteria,
        return <code>false</code>.</li>
    </ul>

  </div></div>

</div><h3 id="Testable_Assertions">Testable Assertions</h3><div class="text">

  <p>In addition to the assertions implied by the functionality requirements
  listed above, the following additional assertions shall be tested to
  validate the behavior of <code>JDBCRealm</code>:</p>
  <ul>
  </ul>

</div><div class="noprint"><h3 id="comments_section">
                  Comments
                </h3><div class="text"><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
                    on improving documentation for Apache Tomcat.<br><br>
                    If you have trouble and need help, read
                    <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
                    and ask your question on the tomcat-users
                    <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
                    Do not ask such questions here. This is not a Q&amp;A section.<br><br>
                    The Apache Comments System is explained <a href="../comments.html">here</a>.
                    Comments may be removed by our moderators if they are either
                    implemented or considered invalid/off-topic.
                  </p><div id="comments_thread"></div></div></div></div></div></div></div><footer><div id="footer">
    Copyright &copy; 1999-2016, The Apache Software Foundation
  </div></footer></div></body></html>